Working with direct to stage digital video in Director

Each digital video sprite has a property called 'directToStage'. This property allows QuickTime or AVI drivers installed on the computer to completely control the video playback. When 'directToStage' is disabled, Director composites the video in an off-screen buffer before displaying it on the stage.

For more information about DTS see Working with direct to stage (TechNote 16770).

When 'directToStage' is enabled digital video sprites display on top of all other sprites on the stage regardless of the channel the sprite is in. Ink effects are not available for video sprites when "directToStage" is enabled. 'DirectToStage' usually yields smooth digital video playback and is enabled by default so the digital video sprite will play at or near its full frame rate. This property can be enabled or disabled via Lingo (see script below) or the AVI/QuickTime tab in the Property Inspector.

Disabling the 'directToStage' property of a digital video member allows other sprites to be layered on top of that member, and also allows the use of transitions and ink effects. Digital video performance usually decreases if 'directToStage' is turned off. The following example show how to set the 'directToStage' property via Lingo:

member("myVideo").directToStage = True

Direct to stage, Play every frame, and soundtracks
A digital video member's soundtrack will not play if both its "directToStage" and "Play every frame" properties are enabled. However, if "directToStage" is enabled for a digital video cast member that does not have a soundtrack, you might choose to enable the "Play every frame" checkbox in the digital video cast member properties dialog box.

When "Play every frame" is enabled, Director will attempt to play every visual frame of the digital video. Whether or not this results in a performance improvement is subjective: if dropped frames are a problem, then "Play every frame" will usually prevent dropped frames. However, depending on the data rate of the digital video, the digital video sprite may not play any more smoothly than before. In addition, playing every frame may cause the digital video to take more time to play.

Cleaning up artifacts
After playing a 'directToStage' digital video sprite, Director may leave an artifact of the video on the stage. The artifact may look like the last frame of the video, a black box, or a fragmented graphic. This only occurs when 'directToStage' is enabled. Director does not automatically redraw the area of the stage previously occupied by the digital video sprite. Below are some methods that may be used to erase artifacts left from a digital video sprite.

The stageColor
The stageColor property can be used to erase video artifacts. When the script below is executed in a frame following the digital video sprite, the stage will be redrawn and artifacts will be erased. This is the most common Lingo technique for cleaning up artifacts, and is typically very effective.

set the stageColor = the stageColor

Transitions
A transition in a frame following the digital video will cause the stage to be redrawn and usually clean up any digital video artifacts. In order for this to work, the "entire stage" option must be used.

Animation
Animating a graphic across the stage after the digital video has played will cause the stage to redraw. This graphic can be transparent or the same as the stage color so that it is not seen by then end user. This method will not work if the digital video has the default QuickTime controller bar displayed. Instead, use the clean up behavior below.

Clean up behavior
Following is a Lingo behavior that can be assigned to a digital video sprite. This behavior will hold the playback head in the current frame until the video is finished playing, then clean up after it (if necessary), and then continue.

Instead of using the Lingo "set the stageColor = the stageColor", the following technique sets the "visible" property of the digital video sprit. The following technique holds the playback head on the frame until the digital video finishes playing, and then cleans up the artifacts.

The behavior will automatically determine the sprite channel number and other sprite and member properties, so you shouldn't need to change the Lingo in this script for it to work. Assign this behavior directly to the digital video sprite.

   --------------------------------------------------------
   -- Play digital video, clean up & then continue.
   
   property myDVSpriteNum, myDVLength
   
   on beginSprite me
     -- Initialization:
     myDVSpriteNum = me.spriteNum
     myDVMember = sprite(myDVSpriteNum).member
    sprite(myDVSpriteNum).visible = TRUE
   myDVLength =member(myDVMember).duration
   end
   
   on exitFrame me
     -- Hold on current frame & play 
     --digital video until end:
     case (TRUE) of
      (sprite(myDVSpriteNum).movieTime < myDVLength):
       go to the frame
     otherwise
       go to the frame + 1
     end case
   end
   
   on endSprite me
     -- Clean up direct to stage digital video sprite:
   sprite(myDVSpriteNum).visible = FALSE
      sprite(myDVSpriteNum).visible = TRUE
   end
   -------------------------------------------------------

Additional information:
Toggling direct to stage of QuickTime video crashes Director (TechNote 16186)
Overlapping QuickTime and Flash sprites cause a flicker (TechNote 3149)